AddFileAttachmentAnnot(Single,Single,Single,Single,Byte[],String,String,String,Byte,Byte,Byte,Single,PdfFileAttachmentAnnotIcon) Method

In This Topic

Adds a file attachment annotation object on the currently selected page of the loaded PDF document. The subtype attribute of this annotation is "FileAttachment". This annotation contains a reference to a file typically embedded in the current document. Opening this annotation you can extract, view or store the attached file.

This method uses the RGB color space for specifying the required color of the annotation object, here it is the background color of the annotation's icon.

Syntax

Visual Basic
C#
Delphi
JScript
Managed Extensions for C++
C++/CLI

'Declaration
 
Public Overloads Function AddFileAttachmentAnnot( _
   ByVal Left As Single, _
   ByVal Top As Single, _
   ByVal Width As Single, _
   ByVal Height As Single, _
   ByVal Data() As Byte, _
   ByVal FileName As String, _
   ByVal Title As String, _
   ByVal Description As String, _
   ByVal Red As Byte, _
   ByVal Green As Byte, _
   ByVal Blue As Byte, _
   ByVal Opacity As Single, _
   ByVal AnnotIcon As PdfFileAttachmentAnnotIcon _
) As Integer

public int AddFileAttachmentAnnot( 
   float Left,
   float Top,
   float Width,
   float Height,
   byte[] Data,
   string FileName,
   string Title,
   string Description,
   byte Red,
   byte Green,
   byte Blue,
   float Opacity,
   PdfFileAttachmentAnnotIcon AnnotIcon
)

public function AddFileAttachmentAnnot( 
    Left: Single;
    Top: Single;
    Width: Single;
    Height: Single;
    Data: Bytearray of;
    FileName: String;
    Title: String;
    Description: String;
    Red: Byte;
    Green: Byte;
    Blue: Byte;
    Opacity: Single;
    AnnotIcon: PdfFileAttachmentAnnotIcon
): Integer;

public function AddFileAttachmentAnnot( 
   Left : float,
   Top : float,
   Width : float,
   Height : float,
   Data : byte[],
   FileName : String,
   Title : String,
   Description : String,
   Red : byte,
   Green : byte,
   Blue : byte,
   Opacity : float,
   AnnotIcon : PdfFileAttachmentAnnotIcon
) : int;

public: int AddFileAttachmentAnnot( 
   float Left,
   float Top,
   float Width,
   float Height,
   byte[]* Data,
   string* FileName,
   string* Title,
   string* Description,
   byte Red,
   byte Green,
   byte Blue,
   float Opacity,
   PdfFileAttachmentAnnotIcon AnnotIcon
)

public:
int AddFileAttachmentAnnot( 
   float Left,
   float Top,
   float Width,
   float Height,
   array<byte>^ Data,
   String^ FileName,
   String^ Title,
   String^ Description,
   byte Red,
   byte Green,
   byte Blue,
   float Opacity,
   PdfFileAttachmentAnnotIcon AnnotIcon
)

Parameters

Left: The horizontal (X) coordinate of the closest point to the currently defined origin, where the annotation's bounding box is to be located. The value is expressed in the current units specified by the SetMeasurementUnit method and it is related to the current page. For further assistance, please see the Remarks section below.
Top: The vertical (Y) coordinate of the closest point to the currently defined origin, where the annotation's bounding box is to be located. The value is expressed in the current units specified by the SetMeasurementUnit method and it is related to the current page. For further assistance, please see the Remarks section below.
Width: The width of the annotation's bounding box, expressed in the current units specified by the SetMeasurementUnit method.
Height: The height of the annotation's bounding box, expressed in the current units specified by the SetMeasurementUnit method.
Data: The binary content of the file associated with the annotation object.
FileName: The name of the file associated with the annotation object.
Title: The title of the newly added annotation object, by convention it represents the author of the annotation.
Description: The description of the file associated with the annotation object.
Red: The amount of red color to be used for the resulting color when displaying an annotation's icon. Use the value between 0 and 255.
Green: The amount of green color to be used for the resulting color when displaying an annotation's icon. Use the value between 0 and 255.
Blue: The amount of blue color to be used for the resulting color when displaying an annotation's icon. Use the value between 0 and 255.
Opacity: The opacity value of the newly added annotation object, from 0 (full transparency) to 1 (full opacity).
AnnotIcon: A member of the PdfFileAttachmentAnnotIcon enumeration. The name of the icon to be used when displaying the annotation.

Return Value

The unique annotation index from 0 to GetAnnotationCount-1 related to the currently selected page. The GetStat method can be subsequently used to determine if this method has been successful.

Remarks

This method is only allowed for use with non-encrypted documents.

It is recommend to use the GetStat method to identify the specific reason for the method's failure, if any.

Please always ensure that you have selected the correct page using the SelectPage method before adding a required annotation.

You also need to be aware that the values of coordinates and dimensions are expressed in the current units defined by the SetMeasurementUnit method according to the current coordinate space defined by the SetOrigin method.

Example

How to create an annotation with the attached file on a new page of the PDF document.

VB.NET
C#

Dim caption As String = "Example: AddFileAttachmentAnnot"
Dim gdpicturePDF As GdPicturePDF = New GdPicturePDF()
If (gdpicturePDF.NewPDF() = GdPictureStatus.OK) AndAlso
   (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft)
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter)
    Dim status As GdPictureStatus = GdPictureStatus.OK
    'Set the filename of the file you want to attach.
    Dim filename As String = "your_file_attachment"
    Dim data As Byte() = Nothing
    Try
        data = IO.File.ReadAllBytes(filename)
    Catch e As Exception
        status = GdPictureStatus.Aborted
        MessageBox.Show("The file to be attached can't be read. Exception: " + e.Message, caption)
    End Try
    If status = GdPictureStatus.OK Then
        'Please always select the required page before adding an annotation.
        If gdpicturePDF.SelectPage(1) = GdPictureStatus.OK Then
            Dim annotID As Integer = gdpicturePDF.AddFileAttachmentAnnot(5, 5, 2, 4, data, filename, "GdPicture", "Attachment for review",
                                                                          255, 165, 0, 0.75F, PdfFileAttachmentAnnotIcon.Paperclip)
            'Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID.
            If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
                Dim annotType As String = gdpicturePDF.GetAnnotationType(annotID)
                Dim status1 As GdPictureStatus = gdpicturePDF.GetStat()
                Dim annotSubtype As String = gdpicturePDF.GetAnnotationSubType(annotID)
                Dim status2 As GdPictureStatus = gdpicturePDF.GetStat()
                Dim message As String = "The annotation has been created with the ID = " + annotID.ToString() + "." + vbCrLf + "type: "
                If status1 = GdPictureStatus.OK Then message = message + annotType Else message = message + status1.ToString()
                message = message + "    subtype: "
                If status2 = GdPictureStatus.OK Then message = message + annotSubtype Else message = message + status2.ToString()
                If gdpicturePDF.SaveToFile("attachment.pdf") = GdPictureStatus.OK Then
                    message = message + vbCrLf + "The file has been saved."
                Else
                    message = message + vbCrLf + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString()
                End If
                MessageBox.Show(message, caption)
            Else
                MessageBox.Show("The AddFileAttachmentAnnot() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
            End If
        Else
            MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
        End If
    End If
Else
    MessageBox.Show("The file can't be created.", caption)
End If
gdpicturePDF.Dispose()

string caption = "Example: AddFileAttachmentAnnot";
GdPicturePDF gdpicturePDF = new GdPicturePDF();
if ((gdpicturePDF.NewPDF() == GdPictureStatus.OK) &&
    (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK))
{
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);
    GdPictureStatus status = GdPictureStatus.OK;
    //Set the filename of the file you want to attach.
    string filename = "your_file_attachment";
    byte[] data = null;
    try
    {
        data = File.ReadAllBytes(filename);
    }
    catch (Exception e)
    {
        status = GdPictureStatus.Aborted;
        MessageBox.Show("The file to be attached can't be read. Exception: " + e.Message, caption);
    }
            
    if (status == GdPictureStatus.OK)
    {
        //Please always select the required page before adding an annotation.
        if (gdpicturePDF.SelectPage(1) == GdPictureStatus.OK)
        {
            int annotID = gdpicturePDF.AddFileAttachmentAnnot(5, 5, 2, 4, data, filename, "GdPicture", "Attachment for review",
                                                               255, 165, 0, 0.75f, PdfFileAttachmentAnnotIcon.Paperclip);
            //Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID.
            if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
            {
                string annotType = gdpicturePDF.GetAnnotationType(annotID);
                GdPictureStatus status1 = gdpicturePDF.GetStat();
                string annotSubtype = gdpicturePDF.GetAnnotationSubType(annotID);
                GdPictureStatus status2 = gdpicturePDF.GetStat();
                string message = "The annotation has been created with the ID = " + annotID.ToString() + ".\ntype: ";
                if (status1 == GdPictureStatus.OK) message = message + annotType; else message = message + status1.ToString();
                message = message + "    subtype: ";
                if (status2 == GdPictureStatus.OK) message = message + annotSubtype; else message = message + status2.ToString();
                if (gdpicturePDF.SaveToFile("attachment.pdf") == GdPictureStatus.OK)
                    message = message + "\nThe file has been saved.";
                else
                    message = message + "\nThe file can't be saved. Status: " + gdpicturePDF.GetStat().ToString();
                MessageBox.Show(message, caption);
            }
            else
                MessageBox.Show("The AddFileAttachmentAnnot() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
        }
        else
            MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
    }
}
else
    MessageBox.Show("The file can't be created.", caption);
gdpicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
Overload List
SelectPage Method
GetAnnotationCount Method
GetAnnotationType Method
GetAnnotationSubType Method
GetFileAttachmentAnnotEmbeddedFile Method